<a id="maven_plugin" class="anchor" href="#maven_plugin">&nbsp;</a>

<h2>Maven Plugin</h2>

<p>To run MockServer as part of your build add the following plugin to your <strong>pom.xml</strong>:</p>

<pre><code class="code xml">&lt;<span class="element">plugin</span>&gt;
    &lt;<span class="element">groupId</span>&gt;<span class="element_value">org.mock-server</span>&lt;/<span class="element">groupId</span>&gt;
    &lt;<span class="element">artifactId</span>&gt;<span class="element_value">mockserver-maven-plugin</span>&lt;/<span class="element">artifactId</span>&gt;
    &lt;<span class="element">version</span>&gt;<span class="element_value">5.11.2</span>&lt;/<span class="element">version</span>&gt;
    &lt;<span class="element">configuration</span>&gt;
        &lt;<span class="element">serverPort</span>&gt;<span class="element_value">1080</span>&lt;/<span class="element">serverPort</span>&gt;
        &lt;<span class="element">logLevel</span>&gt;<span class="element_value">DEBUG</span>&lt;/<span class="element">logLevel</span>&gt;
        &lt;<span class="element">initializationClass</span>&gt;<span class="element_value">org.mockserver.maven.ExampleInitializationClass</span>&lt;/<span class="element">initializationClass</span>&gt;
    &lt;/<span class="element">configuration</span>&gt;
    &lt;<span class="element">executions</span>&gt;
        &lt;<span class="element">execution</span>&gt;
            &lt;<span class="element">id</span>&gt;<span class="element_value">process-test-classes</span>&lt;/<span class="element">id</span>&gt;
            &lt;<span class="element">phase</span>&gt;<span class="element_value">process-test-classes</span>&lt;/<span class="element">phase</span>&gt;
            &lt;<span class="element">goals</span>&gt;
                &lt;<span class="element">goal</span>&gt;<span class="element_value">start</span>&lt;/<span class="element">goal</span>&gt;
            &lt;/<span class="element">goals</span>&gt;
        &lt;/<span class="element">execution</span>&gt;
        &lt;<span class="element">execution</span>&gt;
            &lt;<span class="element">id</span>&gt;<span class="element_value">verify</span>&lt;/<span class="element">id</span>&gt;
            &lt;<span class="element">phase</span>&gt;<span class="element_value">verify</span>&lt;/<span class="element">phase</span>&gt;
            &lt;<span class="element">goals</span>&gt;
                &lt;<span class="element">goal</span>&gt;<span class="element_value">stop</span>&lt;/<span class="element">goal</span>&gt;
            &lt;/<span class="element">goals</span>&gt;
        &lt;/<span class="element">execution</span>&gt;
    &lt;/<span class="element">executions</span>&gt;
&lt;/<span class="element">plugin</span>&gt;</code></pre>

<p>This will start MockServer during the <strong>process-test-classes</strong> phase and will stop MockServer during the <strong>verify</strong> phase. For more details about Maven build phases see:
	<a href="https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html">Introduction to the Build Lifecycle</a>.</p>

<p>This ensures that any integration tests you run during the <strong>test</strong> or <strong>integration-test</strong> phases can use MockServer on the port specified.</p>

<p>It is also possible to run MockServer as a forked JVM using the <span class="annotation">runForked</span> and <span class="annotation">stopForked</span> goals as follows:</p>

<pre><code class="code xml"> &lt;<span class="element">plugin</span>&gt;
     &lt;<span class="element">groupId</span>&gt;<span class="element_value">org.mock-server</span>&lt;/<span class="element">groupId</span>&gt;
     &lt;<span class="element">artifactId</span>&gt;<span class="element_value">mockserver-maven-plugin</span>&lt;/<span class="element">artifactId</span>&gt;
     &lt;<span class="element">version</span>&gt;<span class="element_value">5.11.2</span>&lt;/<span class="element">version</span>&gt;
     &lt;<span class="element">configuration</span>&gt;
        &lt;<span class="element">serverPort</span>&gt;<span class="element_value">1080</span>&lt;/<span class="element">serverPort</span>&gt;
        &lt;<span class="element">logLevel</span>&gt;<span class="element_value">DEBUG</span>&lt;/<span class="element">logLevel</span>&gt;
     &lt;/<span class="element">configuration</span>&gt;
     &lt;<span class="element">executions</span>&gt;
         &lt;<span class="element">execution</span>&gt;
             &lt;<span class="element">id</span>&gt;<span class="element_value">process-test-classes</span>&lt;/<span class="element">id</span>&gt;
             &lt;<span class="element">phase</span>&gt;<span class="element_value">process-test-classes</span>&lt;/<span class="element">phase</span>&gt;
             &lt;<span class="element">goals</span>&gt;
                 &lt;<span class="element">goal</span>&gt;<span class="element_value">runForked</span>&lt;/<span class="element">goal</span>&gt;
             &lt;/<span class="element">goals</span>&gt;
         &lt;/<span class="element">execution</span>&gt;
         &lt;<span class="element">execution</span>&gt;
             &lt;<span class="element">id</span>&gt;<span class="element_value">verify</span>&lt;/<span class="element">id</span>&gt;
             &lt;<span class="element">phase</span>&gt;<span class="element_value">verify</span>&lt;/<span class="element">phase</span>&gt;
             &lt;<span class="element">goals</span>&gt;
                 &lt;<span class="element">goal</span>&gt;<span class="element_value">stopForked</span>&lt;/<span class="element">goal</span>&gt;
             &lt;/<span class="element">goals</span>&gt;
         &lt;/<span class="element">execution</span>&gt;
     &lt;/<span class="element">executions</span>&gt;
 &lt;/<span class="element">plugin</span>&gt;</code></pre>

<p><strong>Stop MockServer Even When Tests Fail</strong></p>

<p>If you use the <span class="annotation">runForked</span> goal as above and the <strong>test</strong> phase fails (because a test has failed) MockServer will not be stopped as Maven does not run any more phases after a phase has failed. In the case above the
	<strong>verify</strong> phase is not run if a test fails so the forked MockServer will not be stopped.</p>

<p>If you want to ensure MockServer is stopped even when there are test failures make sure you use <span class="annotation">start</span> and
	<span class="annotation">stop</span> goals as these run MockServer on a separate thread that is stopped however maven exits (even if a test fails).</p>

<p>Alternatively a TestListener can be used with <span class="annotation">maven-surefire-plugin</span> to ensure that MockServer is stopped even when a test fails, as follows:</p>

<pre><code class="code xml"> &lt;<span class="element">plugin</span>&gt;
    &lt;<span class="element">groupId</span>&gt;<span class="element_value">org.apache.maven.plugins</span>&lt;/<span class="element">groupId</span>&gt;
    &lt;<span class="element">artifactId</span>&gt;<span class="element_value">maven-surefire-plugin</span>&lt;/<span class="element">artifactId</span>&gt;
    &lt;<span class="element">version</span>&gt;<span class="element_value">2.17</span>&lt;/<span class="element">version</span>&gt;
    &lt;<span class="element">configuration</span>&gt;
        &lt;<span class="element">properties</span>&gt;
            &lt;<span class="element">property</span>&gt;
                &lt;<span class="element">name</span>&gt;<span class="element_value">listener</span>&lt;<span class="element">/name</span>&gt;
                &lt;<span class="element">value</span>&gt;<span class="element_value">org.mockserver.maven.StopMockServerTestListener</span>&lt;<span class="element">/value</span>&gt;
            &lt;<span class="element">/property</span>&gt;
        &lt;<span class="element">/properties</span>&gt;
    &lt;/<span class="element">configuration</span>&gt;
&lt;/<span class="element">plugin</span>&gt;</code></pre>

<p>The Maven plugin can also be used from the command line to start and stop MockServer, as follows:</p>

<p>To run MockServer synchronously and block:</p>

<pre><code class="code">mvn mockserver:run</code></pre>

<p>To run MockServer asynchronously as a forked JVM:</p>

<pre><code class="code">mvn mockserver:runForked</code></pre>

<p>To stop a forked instance of MockServer running on the same machine:</p>

<pre><code class="code">mvn mockserver:stopForked</code></pre>

<p>The <strong>stopForked</strong> goal does assumes that MockServer is running on the same physical machine as it uses 127.0.0.1 to communicate with MockServer stop socket.</p>

<p>The Maven plugin has the following goals:</p>

<ul>
	<li>
		<strong>start</strong> - start MockServer, do not block, but stop when build ends
	</li>
	<li>
		<strong>stop</strong> - stop a MockServer started earlier as part of the current build
	</li>
	<li>
		<strong>run</strong> - run MockServer and block waiting for requests (timeout config if provided limits how long to block for)
	</li>
	<li>
		<strong>runForked</strong> - run MockServer as separate forked JVM, do not block, stay alive when build ends
	</li>
	<li>
		<strong>stopForked</strong> - stop a forked MockServer, previously started by a runForked goal
	</li>
</ul>
<p>The Maven plugin can be configured with the following properties:</p>

<ul>
	<li>
		<strong>serverPort</strong> - The port the MockServer listens for incoming request.  Port unification is used to support both HTTP and HTTPS on the same port (required: true)
	</li>
	<li>
		<strong>proxyRemotePort</strong> - The port proxied requests are forwarded to (required: false)
	</li>
	<li>
		<strong>proxyRemoteHost</strong> - The host proxied requests are forwarded to (required: false)
	</li>
	<li>
		<strong>timeout</strong> - How long to block waiting for MockServer, after the timeout the plugin will shutdown MockServer, used by <strong>run</strong> goal, 0 means wait indefinitely (required: false, default: 0)
	</li>
	<li>
		<strong>logLevel</strong> - The logging level (required: false, default: INFO)
	</li>
	<li>
		<strong>skip</strong> - Prevent the plugin from running (required: false, default: false)
	</li>
	<li>
		<strong>initializationClass</strong> - To enable the creation of default expectations a class can be specified to initialize expectations in MockServer, this class must implement <span class="inline_code">org.mockserver.client.initialize.PluginExpectationInitializer</span> interface. The
		<span class="inline_code">initializeExpectations(MockServerClient mockServerClient)</span> method will be called once MockServer has been started. Note: that the plugin must be started during the
		<strong>process-test-classes</strong> to ensure that the initialization class has been compiled from either <strong>src/main/java</strong> or <strong>src/test/java</strong> locations. In addition the initializer can only be used with <strong>start</strong> and
		<strong>run</strong> goals, it will not work with the <strong>runForked</strong> goal as a JVM is forked with a separate classpath. (required: false, default: false)
	</li>
</ul>

<a id="client_api" class="anchor" href="#client_api">&nbsp;</a>

<h2>Client API&nbsp;&nbsp;-&nbsp;&nbsp;starting and stopping</h2>

<p>Use the client API to run MockServer programmatically.</p>

<p>First add the following maven dependency:</p>

<pre><code class="code xml">&lt;!-- mockserver --&gt;
&lt;<span class="element">dependency</span>&gt;
     &lt;<span class="element">groupId</span>&gt;<span class="element_value">org.mock-server</span>&lt;<span class="element">/groupId</span>&gt;
     &lt;<span class="element">artifactId</span>&gt;<span class="element_value">mockserver-netty</span>&lt;<span class="element">/artifactId</span>&gt;
     &lt;<span class="element">version</span>&gt;<span class="element_value">5.11.2</span>&lt;<span class="element">/version</span>&gt;
&lt;<span class="element">/dependency</span>&gt;</code></pre>

<p>To start the server or proxy create a client, for example by using one of the start factory methods <span class="inline_code">ClientAndServer.startClientAndServer</span> as follows:</p>

<p>Add includes:</p>

<pre><code class="code"><span class="keyword">import static</span> org.mockserver.integration.ClientAndServer.startClientAndServer;</code></pre>

<p>Add fields:</p>

<pre><code class="code"><span class="keyword">private</span> ClientAndServer <span class="this_value">mockServer</span>;</code></pre>

<p>Use factory method to start server and client when appropriate, for example in <span class="annotation">@Before</span> method:</p>

<pre><code class="code"><span class="annotation">@Before</span>
<span class="keyword">public void</span> startMockServer() {
    <span class="this_value">mockServer</span> = startClientAndServer(<span class="numeric_literal">1080</span>);
}</code></pre>

<p>Stop server and client when appropriate, for example in <span class="annotation">@After</span> method:</p>

<pre><code class="code"><span class="annotation">@After</span>
<span class="keyword">public void</span> stopMockServer() {
    <span class="this_value">mockServer</span>.stop();
}</code></pre>

<p>The <a href="https://github.com/mock-server/mockserver/tree/master/mockserver-examples">mockserver-example</a> project contains an example test called
	<a href="https://github.com/mock-server/mockserver/blob/master/mockserver-examples/src/test/java/org/mockserver/examples/proxy/web/controller/BooksPageIntegrationTest.java">BookPageIntegrationTest</a> that demonstrates a fully working example.</p>

<a id="junit_rule" class="anchor" href="#junit_rule">&nbsp;</a>

<h2>Running MockServer via a JUnit 4 @Rule</h2>

<p>MockServer can be run using the <strong>MockServerRule</strong>. The <strong>MockServerRule</strong> starts MockServer (<strong>for both mocking and proxying</strong>) on a free port before the any test runs and stops MockServer after all tests have completed.</p>
<p>An instance of <strong>MockServerClient</strong> is assigned to any field in the unit test of type <strong>org.mockserver.client.MockServerClient</strong>. Alternatively an instance of <strong>MockServerClient</strong> can be retrieved from the <strong>MockServerRule</strong> using the method <strong>getClient()</strong>.</p>

<pre><code class="code"><span class="annotation">@Rule</span>
<span class="keyword">public</span> MockServerRule mockServerRule = <span class="keyword">new</span> MockServerRule(<span class="keyword">this</span>);

<span class="keyword">private</span> MockServerClient mockServerClient;</code></pre>

<p>The MockServerRule can be added to your project by including the following maven dependency:</p>

<pre class="prettyprint lang-xml code"><code class="code">&lt;dependency&gt;
    &lt;groupId&gt;org.mock-server&lt;/groupId&gt;
    &lt;artifactId&gt;mockserver-junit-rule&lt;/artifactId&gt;
    &lt;version&gt;5.11.2&lt;/version&gt;
&lt;/dependency&gt;</code></pre>

<p>Any test method can now use the <strong>mockServerClient</strong> field to <a href="/mock_server/getting_started.html#setup_expectations">create expectation</a> or <a href="/mock_server/verification.html">verify</a> requests.</p>

<p>The MockServerRule has the following constructors:</p>

<pre><code class="code"><span class="comment">/**
 * Start MockServer prior to test execution and stop MockServer after the tests have completed.
 * This constructor dynamically allocates a free port for MockServer to use.
 *
 * <span class="javadoc_param_annotation">@param</span> <span class="javadoc_param_name">target</span> an instance of the test being executed
 */</span>
<span class="keyword">public</span> MockServerRule(Object target);

<span class="comment">/**
 * Start MockServer prior to test execution and stop MockServer after the tests have completed.
 * This constructor dynamically allocates a free port for MockServer to use.
 *
 * <span class="javadoc_param_annotation">@param</span> <span class="javadoc_param_name">target</span> an instance of the test being executed
 * <span class="javadoc_param_annotation">@param</span> <span class="javadoc_param_name">perTestSuite</span> indicates how many instances of MockServer are created
 *                     if true a single MockServer is created per JVM
 *                     if false one instance per test class is created
 */</span>
<span class="keyword">public</span> MockServerRule(Object target, <span class="keyword">boolean</span> per TestSuite);
<span class="comment">/**
 * Start the proxy prior to test execution and stop the proxy after the tests have completed.
 * This constructor dynamically create a proxy that accepts HTTP(S) requests on the specified port
 *
 * <span class="javadoc_param_annotation">@param</span> <span class="javadoc_param_name">target</span> an instance of the test being executed
 * <span class="javadoc_param_annotation">@param</span> <span class="javadoc_param_name">port</span> the HTTP(S) port for the proxy
 */</span>
<span class="keyword">public</span> MockServerRule(Object target, Integer... ports);

<span class="comment">/**
 * Start the proxy prior to test execution and stop the proxy after the tests have completed.
 * This constructor dynamically create a proxy that accepts HTTP(S) requests on the specified port
 *
 * <span class="javadoc_param_annotation">@param</span> <span class="javadoc_param_name">target</span> an instance of the test being executed
 * <span class="javadoc_param_annotation">@param</span> <span class="javadoc_param_name">perTestSuite</span> indicates how many instances of MockServer are created
 * <span class="javadoc_param_annotation">@param</span> <span class="javadoc_param_name">port</span> the HTTP(S) port for the proxy
 *                     if true a single MockServer is created per JVM
 *                     if false one instance per test class is created
 */</span>
<span class="keyword">public</span> MockServerRule(Object target, <span class="keyword">boolean</span> per TestSuite, Integer... ports);</code></pre>

<a id="junit_test_extension" class="anchor" href="#junit_test_extension">&nbsp;</a>

<h2>Running MockServer via a JUnit 5 Test Extension</h2>

<p>MockServer can be run using the Test Extension <strong>MockServerExtension</strong>. The <strong>MockServerExtension</strong> starts MockServer (<strong>for both mocking and proxying</strong>) before the any test runs and stops MockServer after all tests have completed.</p>
<p>The port(s) MockServer uses can be controlled using <strong>MockServerSettings</strong></p>
<p>An instance of <strong>MockServerClient</strong> or <strong>ClientAndServer</strong> is injected into any method using <a href="https://junit.org/junit5/docs/current/user-guide/#extensions-parameter-resolution">Parameter Resolution</a> this includes: constructors, lifecycle methods (like <span class="annotation">@BeforeEach</span> / <span class="annotation">@BeforeAll</span>), or test methods.</p>

<p>The <strong>MockServerExtension</strong> Test Extension can be added to your project by including the following maven dependency:</p>

<pre class="prettyprint lang-xml code"><code class="code">&lt;dependency&gt;
    &lt;groupId&gt;org.mock-server&lt;/groupId&gt;
    &lt;artifactId&gt;mockserver-junit-jupiter&lt;/artifactId&gt;
    &lt;version&gt;5.11.2&lt;/version&gt;
&lt;/dependency&gt;</code></pre>

<p>The following code examples show how to use the <strong>MockServerExtension</strong> Test Extension.</p>
<button id="button_test_extension_specific_ports" class="accordion">configure specific ports</button>
<div class="panel"><pre class="prettyprint lang-java code"><code class="code">@ExtendWith(MockServerExtension.class)
@MockServerSettings(ports = {8787, 8888})
class ExampleTestClass {
    private final ClientAndServer client;

    public ExampleTestClass(ClientAndServer client) {
        this.client = client;
    }

    @Test
    void testSomething() {
        // ...
    }

}</code></pre></div>
<button id="button_test_extension_constructor_client_injection" class="accordion">inject MockServerClient into constructor</button>
<div class="panel"><pre class="prettyprint lang-java code"><code class="code">@ExtendWith(MockServerExtension.class)
class ExampleTestClass {
    private final ClientAndServer client;

    public ExampleTestClass(ClientAndServer client) {
        this.client = client;
    }

    @Test
    void testSomething() {
        // ...
    }

}</code></pre></div>
<button id="button_test_extension_lifecyle_method_client_injection" class="accordion">inject MockServerClient inject to @BeforeEach</button>
<div class="panel"><pre class="prettyprint lang-java code"><code class="code">@ExtendWith(MockServerExtension.class)
class ExampleTestClass {
    private MockServerClient client;

    @BeforeEach
    public void beforeEachLifecyleMethod(MockServerClient client) {
        this.client = client;
    }

    @Test
    void testSomething() {
        // ...
    }

}</code></pre></div>
<button id="button_test_extension_test_method_client_injection" class="accordion">inject MockServerClient inject to test method</button>
<div class="panel"><pre class="prettyprint lang-java code"><code class="code">@ExtendWith(MockServerExtension.class)
class ExampleTestClass {

    @Test
    void testSomething(MockServerClient client) {
        // ...
    }

}</code></pre></div>
<a id="running_from_command_line" class="anchor" href="#running_from_command_line">&nbsp;</a>

<a id="spring_test_exec_listener" class="anchor" href="#spring_test_exec_listener">&nbsp;</a>

<h2>Running MockServer via Spring TestExecutionListener @MockServerTest</h2>

<p>MockServer can be run using <strong><code>@MockServerTest</code></strong>. The <strong><code>mockserver-spring-test-listener</code></strong> dependency registers a Spring <code>TestExecutionListener</code> which starts MockServer on a free port if the test class is annotated with <strong><code>@MockServerTest</code></strong>. MockServer is reset after each test and closed after all tests via a shutdown hook.</p>
<p>As the MockServer instance is shared between all test classes <strong><code>@MockServerTest</code></strong> does not support parallel test execution, unless each test uses a <a href="/mock_server/running_tests_in_parallel.html">unique value in each request matcher</a>.</p>

<p>The TestExecutionListener with <strong><code>@MockServerTest</code></strong> can be added to your project by including the following maven dependency:</p>

<pre class="prettyprint lang-xml code"><code class="code">&lt;dependency&gt;
    &lt;groupId&gt;org.mock-server&lt;/groupId&gt;
    &lt;artifactId&gt;mockserver-spring-test-listener&lt;/artifactId&gt;
    &lt;version&gt;5.11.2&lt;/version&gt;
&lt;/dependency&gt;</code></pre>

<p>An instance of <strong><code>MockServerClient</code></strong> is assigned to any field in the unit test of type <strong><code>org.mockserver.client.MockServerClient</code></strong>.</p>

<pre><code class="prettyprint lang-java code">@MockServerTest
@RunWith(SpringRunner.class)
public class ExampleSpringTestListenerTestWithClientInjection {

    private MockServerClient mockServerClient;

    @Test
    public void testSomething() {
        // test code
    }

}</code></pre>

<p>If you want to configure a client (Spring Bean) to use MockServer you can create a test property with <code>${mockServerPort}</code> placeholder. This is replaced by the chosen free port for MockServer.</p>

<pre><code class="prettyprint lang-java code">@RunWith(SpringRunner.class)
@MockServerTest("server.url=http://localhost:${mockServerPort}/path")
@ContextConfiguration(classes = MockServerTestFullSampleTest.Config.class)
public class ExampleSpringTestListenerTestWithUrlInjection {

    static class Client {
        @Value("${server.url}")
        private URI serverUrl;

        private final RestTemplate restTemplate = new RestTemplate();

        @Nullable
        public &lt;T&gt; T getResult(String path, Class&lt;T&gt; responseType) {
            return restTemplate.getForObject(serverUrl + path, responseType);
        }
    }

    static class Config {
        @Bean
        public Client client() {
            return new Client();
        }
    }

    @Autowired
    private Client client;

    private MockServerClient mockServerClient;

    @Test
    public void testSomething() {
        // test code
    }

}</code></pre>

<p>The free port itself is also added as test property and can be retrieved with <code>@MockServerPort</code>.</p>

<pre><code class="prettyprint lang-java code">@MockServerTest
@RunWith(SpringRunner.class)
public class ExampleSpringTestListenerTestWithPortInjection {

    @MockServerPort
    Integer mockServerPort;

    @Test
    public void testSomething() {
        // test code
    }

}</code></pre>

<h2>Running From Command Line</h2>

<p>MockServer can be run from the command line in the following ways:</p>

<ul>
	<li><a href="#running_from_command_line_using_homebrew">using homebrew</a> i.e. <strong>brew install mockserver && mockserver</strong></li>
	<li><a href="#running_from_command_line_using_java">using java directly</a> i.e. <strong>java -jar mockserver-netty-5.11.2-jar-with-dependencies.jar</strong></li>
	<li><a href="#running_from_command_line_using_maven_plugin">using maven plugin</a> i.e. <strong>mvn org.mock-server:mockserver-maven-plugin:5.11.2:runForked</strong></li>
	<li><a href="#docker_container">using docker</a> i.e. <strong>docker run -d --rm -p mockserver/mockserver</strong></li>
</ul>

<a id="running_from_command_line_using_homebrew" class="anchor" href="#running_from_command_line_using_homebrew">&nbsp;</a>

<h3>Running From Command Line - Using Homebrew</h3>

<p><a href="https://brew.sh/">Homebrew</a>, a packaging manager for OS X (i.e. Apple Mac), can be used to install MockServer, as follows:</p>

<pre><code class="code">brew install mockserver</code></pre>

<p>The MockServer formula in Homebrew performs the following actions:</p>

<ol>
	<li>installed the binaries and scripts</li>
	<li>creates the log directory</li>
	<li>add the scripts to the PATH variable</li>
</ol>

<p>Once the MockServer has been installed by Homebrew it is available from any command shell as the <strong>mockserver</strong> command</p>

<p>The <strong>mockserver</strong> command supports the following options:</p>

<pre><code class="code">mockserver -serverPort <span class="command_line_argument_placeholder">&lt;port&gt;</span> [-proxyRemotePort <span class="command_line_argument_placeholder">&lt;port&gt;</span>]  [-proxyRemoteHost <span class="command_line_argument_placeholder">&lt;hostname&gt;</span>] [-logLevel <span class="command_line_argument_placeholder">&lt;level&gt;</span>] [-jvmOptions <span class="command_line_argument_placeholder">&lt;system parameters&gt;</span>]

 valid options are:
    -serverPort <span class="command_line_argument_placeholder">&lt;port&gt;</span>           The HTTP, HTTPS, SOCKS and HTTP CONNECT
                                 port(s) for both mocking and proxying
                                 requests.  Port unification is used to
                                 support all protocols for proxying and
                                 mocking on the same port(s). Supports
                                 comma separated list for binding to
                                 multiple ports.

    -proxyRemotePort <span class="command_line_argument_placeholder">&lt;port&gt;</span>      Optionally enables port forwarding mode.
                                 When specified all requests received will
                                 be forwarded to the specified port, unless
                                 they match an expectation.

    -proxyRemoteHost <span class="command_line_argument_placeholder">&lt;hostname&gt;</span>  Specified the host to forward all proxy
                                 requests to when port forwarding mode has
                                 been enabled using the proxyRemotePort
                                 option.  This setting is ignored unless
                                 proxyRemotePort has been specified. If no
                                 value is provided for proxyRemoteHost when
                                 proxyRemotePort has been specified,
                                 proxyRemoteHost will default to \"localhost\".

    -logLevel <span class="command_line_argument_placeholder">&lt;level&gt;</span>            Optionally specify log level using SLF4J levels:
                                 TRACE, DEBUG, INFO, WARN, ERROR, OFF or Java
                                 Logger levels: FINEST, FINE, INFO, WARNING,
                                 SEVERE or OFF. If not specified default is INFO

    -jvmOptions <span class="command_line_argument_placeholder">&lt;level&gt;</span>          Specified generic JVM options or system properties.

i.e. mockserver -logLevel INFO -serverPort <span class="numeric_literal">1080,1081</span> -proxyRemotePort <span class="numeric_literal">80</span> -proxyRemoteHost www.mock-server.com</code></pre>

<p>For example run the MockServer, as follows:</p>

<pre><code class="code">mockserver -logLevel INFO -serverPort <span class="numeric_literal">1080</span></code></pre>

<a id="running_from_command_line_using_java" class="anchor" href="#running_from_command_line_using_java">&nbsp;</a>

<h3>Running From Command Line - Using Java</h3>

<p>MockServer can be run directly from the command line using java directly as follow:</p>

<ol>
	<li><p>download <a href="https://search.maven.org/remotecontent?filepath=org/mock-server/mockserver-netty/5.11.2/mockserver-netty-5.11.2-jar-with-dependencies.jar">mockserver-netty-5.11.2-jar-with-dependencies.jar</a> from Maven Central</p></li>
	<li>
		<code class="code inline">java -jar <span class="command_line_argument_placeholder">&lt;path to mockserver-netty-5.11.2-jar-with-dependencies.jar&gt;</span> -serverPort <span class="command_line_argument_placeholder">&lt;port&gt;</span></code>
	</li>
</ol>

<p>The command line supports the following options:</p>

<pre><code class="code">java -jar <span class="command_line_argument_placeholder">&lt;path to mockserver-jetty-jar-with-dependencies.jar&gt;</span> -serverPort <span class="command_line_argument_placeholder">&lt;port&gt;</span> [-proxyRemotePort <span class="command_line_argument_placeholder">&lt;port&gt;</span>] [-proxyRemoteHost <span class="command_line_argument_placeholder">&lt;hostname&gt;</span>] [-logLevel <span class="command_line_argument_placeholder">&lt;level&gt;</span>]

 valid options are:
    -serverPort <span class="command_line_argument_placeholder">&lt;port&gt;</span>           The HTTP, HTTPS, SOCKS and HTTP CONNECT
                                 port(s) for both mocking and proxying
                                 requests.  Port unification is used to
                                 support all protocols for proxying and
                                 mocking on the same port(s). Supports
                                 comma separated list for binding to
                                 multiple ports.

    -proxyRemotePort <span class="command_line_argument_placeholder">&lt;port&gt;</span>      Optionally enables port forwarding mode.
                                 When specified all requests received will
                                 be forwarded to the specified port, unless
                                 they match an expectation.

    -proxyRemoteHost <span class="command_line_argument_placeholder">&lt;hostname&gt;</span>  Specified the host to forward all proxy
                                 requests to when port forwarding mode has
                                 been enabled using the proxyRemotePort
                                 option.  This setting is ignored unless
                                 proxyRemotePort has been specified. If no
                                 value is provided for proxyRemoteHost when
                                 proxyRemotePort has been specified,
                                 proxyRemoteHost will default to \"localhost\".

    -logLevel <span class="command_line_argument_placeholder">&lt;level&gt;</span>            Optionally specify log level using SLF4J levels:
                                 TRACE, DEBUG, INFO, WARN, ERROR, OFF or Java
                                 Logger levels: FINEST, FINE, INFO, WARNING,
                                 SEVERE or OFF. If not specified default is INFO

i.e. java -jar ./mockserver-jetty-jar-with-dependencies.jar -serverPort <span class="numeric_literal">1080</span> -proxyRemotePort <span class="numeric_literal">80</span> -proxyRemoteHost www.mock-server.com</code></pre>

<p>For example:</p>

<pre><code class="code">java -jar ~/Downloads/mockserver-netty-5.11.2-jar-with-dependencies.jar -serverPort <span class="numeric_literal">1080,1081</span> -logLevel INFO</code></pre>

<p>All interactions with the MockServer are logged including setting up expectations, matching expectations, clearing expectations and verifying requests.  This log information can be particularly helpful when trying to debug why a test is failing or expectations are not being matched.</p>

<p>The argument <span class="inline_code">logLevel</span> can be used to set the <a href="/mock_server/debugging_issues.html#logging-levels">log level</a>, as shown above. It is also possible to further customise where loggers send log events by overriding the default <a href="/mock_server/debugging_issues.html#configure_java_logger">logging configuration</a>.</p>

<a id="running_from_command_line_using_maven_plugin" class="anchor" href="#running_from_command_line_using_maven_plugin">&nbsp;</a>

<h3>Running From Command Line - Using Maven Plugin</h3>

<p>MockServer can be run directly from the command line and using the <strong>mockserver-maven-plugin</strong> as follow:</p>

<pre><code class="code">mvn -Dmockserver.serverPort=<span class="numeric_literal">1080</span> -Dmockserver.logLevel=INFO org.mock-server:mockserver-maven-plugin:5.11.2:runForked</code></pre>

<p>When run from the command line the Maven plugin can be configured with the following properties:</p>

<ul>
	<li>
		<strong>mockserver.serverPort</strong> - The port the MockServer listens for incoming request. Port unification is used to support both HTTP and HTTPS and proxying on the same port (required: false)
	</li>
	<li>
		<strong>mockserver.logLevel</strong> - The logging level (required: false, default: INFO)
	</li>
</ul>

<p>The <span class="annotation">runForked</span> goal of the <strong>mockserver-maven-plugin</strong> will fork a JVM process containing the Netty based MockServer. To stop the forked JVM process use the <span class="annotation">stopForked</span> goal, as follows:</p>

<pre><code class="code">mvn -Dmockserver.serverPort=<span class="numeric_literal">1080</span> org.mock-server:mockserver-maven-plugin:5.11.2:stopForked</code></pre>

<p>For more information on the <strong>mockserver-maven-plugin</strong> see the section on <a href="#maven_plugin">MockServer Maven Plugin</a></p>

<a id="deployable_war" class="anchor" href="#deployable_war">&nbsp;</a>

<h2>Web Archive (WAR)</h2>

<p>To run as a WAR deployed on any JEE web server:</p>

<ol>
	<li>download <a href="https://search.maven.org/remotecontent?filepath=org/mock-server/mockserver-war/5.11.2/mockserver-war-5.11.2.war">mockserver-war-5.11.2.war</a> from Maven Central</li>
	<li>deploy <strong>mockserver-war-5.11.2.war</strong> to any JEE web server</li>
</ol>

<p><strong>WAR Context Path</strong></p>

<p>The WAR context path is ignored from all request matching for path.</p>

<p>The MockServerClient constructor includes an argument for the context path that the WAR has been deployed to, as follows:</p>

<pre><code class="code"><span class="keyword">public</span> MockServerClient(String host, <span class="keyword">int</span> port, String contextPath)</code></pre>

<a id="mockserver_node" class="anchor" href="#mockserver_node">&nbsp;</a>

<h2>NPM Module & MockServer Grunt Plugin</h2>

{% include_subpage ../mock_server/_includes/running_npm_module.html %}

<a id="docker_container" class="anchor" href="#docker_container">&nbsp;</a>

<h2>Docker Container</h2>

{% include_subpage ../mock_server/_includes/running_docker_container.html %}

<a id="helm_chart" class="anchor" href="#helm_chart">&nbsp;</a>

{% include_subpage ../mock_server/_includes/helm_chart.html %}

<a id="build-and-run-from-source" class="anchor" href="#build-and-run-from-source">&nbsp;</a>

<h2>Build & Run From Source</h2>

<p>MockServer is written in Java and built using maven.  The maven wrapper is used so maven does not need to be installed but Java JDK 8 or higher does need to be installed.</p>

<p>First clone the repository as follows:</p>

<pre><code class="code">git clone https://github.com/jamesdbloom/mockservice.git
cd mockserver</code></pre>

<p>Next use <strong>maven</strong> to build an executable jar containing all dependencies as follows:</p>

<pre><code class="code">./mvnw clean package</code></pre>

<p>This will produce a jar file under the target directory called, as follows:</p>

<pre><code class="code">mockserver-netty/target/mockserver-netty-5.11.2-jar-with-dependencies.jar</code></pre>

<p>Run MockServer then using the executable jar as per the instruction above in <a href="#running_from_command_line">Running From The Command Line</a></p>
